Images Tool

Usage:
images --create -o <path> {--ar <lags>} {--png} {--dot} {--noxml}
  {--discount <discount>} {--listtype all|max} -p <outprefix>
  -d <path1> ... <pathn>
images --count -o <path> -p <outprefix>
images --convert --ar <lags> -o <path> -d <path1> ... <pathn>

The create command takes a list of tab-delimited data sets of the form

X1  X2  ... Xm
d11 d12 ... d1m
...
dn1 dn2 ... dnm

that share the same variables in the same order and have the same
number of cases, optionally substitutes their AR residuals, runs
iMAGES on them with the given (optional) penalty discount, and
deposits into the output directory, for the output CPDAG and for
each DAG consistent with that CPDAG with the maximum totalScore, a
(relodable) XML file for the graph. CPDAG files will suffixed
.cpdag.xml (.cpdag.png, .cpdag.dot); maximum-totalScore DAG files
will be indexed and suffixed--e.g. run1.1.dag.xml, etc. If --png is
specified, PNG image files of the graphs will be added to the output
directory, similarly suffixed--e.g. run1.1.dag.png; if --dot is
specified, DOT files for the graphs will be added, similarly
suffixed--e.g. run1.1.dag.dot.  Counting can, however, be done only
over files in the graph XML format.

The count command will read in all of the .graph.xml files in the
output directory and count the number of such graphs each adjacency
and each edge is in, and output these counts to a file with the given
name, with suffix counts.txt.

The convert command will read in a list of data files, perform a
specified conversion on them (now only AR residuals is available) and
output the files prefixed by "ar_" in to the -o directory.

--create Runs images on a list of data sets,
--count Counts the number of times each edge occurs in graphs in the output
  path whose filename contains the given label, specified using -l.
--convert Converts files from one form to another.
--search Searches for a penalty discount from -mindiscount upward in
increments of -increment for the first penalty discount that produces
an output graph with no triangles. The default will be to search
using a minimum discount of 0.5 upward increments of 0.5; for other
minimum discounts and increments, use the --mindiscount and
-o Specifies the output directory.
-p Output files will be given a name with this prefix, with various
suffixes.
-d A list of paths to datasets, by default columnwise, tab-delimited,
  with variable names in the first row.
--verbose Prints verbose output from searches.
--novars For parsing the data, assumes there are no variables in the first
row of the data.
--nodags If selected, DAGs will not be generated from the IMaGES CPDAG;
instead, only the IMaGES CPDAG and its adjacency matrix will be output.
--csv Sets the delimiter character for data to tab.
--images.lofs Runs IMaGES, as above, followed by LOFS.
--depErrorsAlpha Specifies the depErrorsAlpha for residual nongaussianity above which
orientation inferences are not made.
--r1 Do rule R1 for LOFS. If neither R1 nor R2 is chosen R1 will be used
by default.
--r2 Do rule R2 for LOFS. If both R1 and R2 are chosen, R1 is done before R2.
--strong Use the strong (as opposed to the default weak) form of R2.
By default, the weak form is used.
--keep2c When following R1 by R2, any 2 cycles found by R1 are kept.
By default, 2 cycles from R1 are overwritten by R2.
--mc Mean center residuals before mixing them. By default, residuals
are not mean centered prior to mixing.
--ar Substitutes AR residuals of data for data.
--discount Penalty discount for iMAGES. If not specified, the default is 1.
--png Optionally creates a PNG images for the graph.
--dot Optionally creates a DOT specification for the graph.
--noxml Leaves the graphical XML files out of the output directory. Note
  that no counting of graphs can be done if these are left out.
--listtype all|max Lists either all of the dags in the CPDAG, or just
  those with the maximum totalScore. The default is max.
--knowledge <path> The path to a knowledge file, if appropriate. The
  knowledge file specifies edges that are forbidden or required. See
  example below.
--mindiscount For search, the minimum discount considered. Default = 0.5.
--increment For search, the increment by which discounts are increased until
a nontriangular graph is found. Default = 0.5.

Examples.

images --create -o runsdir --ar --discount 5 -p run1 --dot -d
data/*run001.txt

This creates runsdir if it's not already created and puts the
following files into it:

run1.dot
run1.graph.xml

Likewise,

images --create -o runsdir --ar -discount 1 -p run2 -d --png -d
data/*run002.txt

will add these files to runsdir:

run2.png
run2.graph.xml

Now we can count:

images --count -o runsdir -p run12

reads in run1.graph.xml and run2.graph.xml, counts edges,and adds to
runsdir this file:

run12.counts.txt

containing edge counts for runs 1 and 2.              

images --convert --ar 2 -o newout -d *run002.txt

converts all of the data sets in *run002.txt into their AR residuals data sets.

images --search -p run3 -d data/*run002.txt

Searches in sequence starting with minimum discount of 0.5 and increasing
the discount by 0.5 each time until a graph with no triangles is found.

images --search --mindiscount 1 --increment 0.1 -p run3 -d data/*run002.txt

Same, but with specified minimim penalty discount and increment.

An example of a knowledge file:

/knowledge
addtemporal
1 X4 X5
2 X1 X3
3 X2

forbiddirect
X4 X5

requiredirect
X3 X2
X1 X2

The sections of the file must appear in this order, if included, but
any of them may be omitted. The addtemporal section specifies
knowledge tiers; any edge from a later tier to an earlier tier is
forbidden. The forbiddirect section specifies particular forbidden
edges--in this case, X4-->X5. The requiredirect section specifies
psrticular required edges--in this case, X3-->X3 and X1-->X2. The
information any section many not contradict the information in any
other section.
